BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / programs / sapphire.zip / SAPPHIRE.DOC < prev next >

Wrap

Text File | 1992-01-14 | 64KB | 2,250 lines

S A P P H I R E COMPUTER BULLETIN BOARD SYSTEM Release: 4.00A Operation Manual PINNACLE SOFTWARE, Box 714 Airport Road, Swanton VT 05488 USA PINNACLE SOFTWARE, CP 386 TMR, Quebec, Canada H3P 3C6 CUSTOMER SERVICE LINE (VOICE): (514) 345-9578 DATA LINE (9600 baud, V42bis): (514) 345-8654 ===================================== LEGAL NOTICES AND SUPPORT INFORMATION ===================================== Shareware and Registration -------------------------- This version of Sapphire is distributed as shareware. With respect to Sap- phire, "shareware" means that you may try out the program for 45 days without paying for it. If you continue to use it after that time, though, you are indicating that the product fulfils your needs and as such you are legally required to register it ($45). When you register Sapphire, you gain the following benefits: - You get a disk containing the most recent version of Sapphire available - The "Program under evaluation" message disappears from your BBS - You get bonus software sent along with the registered Sapphire - You get substantial discounts on our other products - You get privileged access to our free files BBS - You get privileged access to our voice support line - You get unscheduled news mailings and software samples - You get access to Sapphire source code (extra fees may apply here) - You help keep down the high cost of software -- by supporting shareware! Shareware terms do not extend to the source code of Sapphire, nor to later versions, nor accessories, unless they are declared as shareware by Pinnacle Software. Sapphire is Copyright (C) 1986, 1992 by Pinnacle Software. Turbo Pascal is a Trademark of Borland International. DSZ is a Trademark of Omen Technology. ii Support for Registered Sysops ----------------------------- The Sapphire release number follows this pattern: Version Number Internal ID | | 4 . 0 0 A / \ Upgrade Level Correction Level A registered Sapphire owner is entitled to operate any release of Sapphire with the same Version and Upgrade Level, and the same or different Internal ID or Correction Level. Thus, corrections to the program ("bug fixes") can be obtained at no cost by downloading them from our support board, or for a $3 shipping fee, by mail. Installation and Trouble-Shooting --------------------------------- For complete information about installation and trouble-shooting, refer to the INFO section of the SYSOP utility that accompanies Sapphire (type SYSOP at the DOS prompt). The information there can be viewed online or printed to LPT1 or LPT2. If you are installing Sapphire for the first time, you may call Pinnacle Software for assistance if you can not complete the basic installation success- fully. But you may be able to save yourself time and long-distance charges: experience has shown us that 90% of all installation problems can be solved by the advice in the trouble-shooting section of the SYSOP utility. Upgrading From Earlier Versions ------------------------------- Refer to the INSTALL article in the INFO section of the SYSOP utility for instructions for upgrading from earlier versions of Sapphire. iii ================= TABLE OF CONTENTS ================= LEGAL NOTICES AND SUPPORT INFORMATION . . . . . . . . . . . . . . . . . . ii Shareware and Registration Support for Registered Sysops Installation and Trouble-Shooting Upgrading From Earlier Versions BASIC SYSTEM OPERATION . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Duties of the System Operator Signing on Locally Signing on as SYSOP Function Keys The Status Line Online Validation and Banishment Yoo-Hoo and Rename AUTO-MAINTENANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 User File Auto-Maintenance Message File Auto-Maintenance Library Auto-Maintenance Files Auto-Maintenance CUSTOMIZING YOUR SYSTEM'S APPEARANCE . . . . . . . . . . . . . . . . . . . 8 An Overview of Your Customization Options Option 1. Configuration Option 2. Application Option 3. Hardware Option 4. Stock Files Option 5. Message Bases Option 6. Doors and Events Option 7. Custom Programming CUSTOMIZING MEMBERSHIP LEVELS . . . . . . . . . . . . . . . . . . . . . . 13 Overview of Membership Levels Why Change Anything? The COMMANDS.LEV File Default Membership Design CUSTOMIZING STOCK FILES . . . . . . . . . . . . . . . . . . . . . . . . . 18 The Two Types of Stock Files Drawing with Graphic Characters Stock File Naming Convention Stock File Commands iv DOORS AND EVENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Definitions Applications for Event Processing Applications for Doors Processing Coding Your Batch Files Writing Door and Event Programs FILE TRANSFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 What is File Transfer? Installing File Transfer Adding Software Locally Adding Software Remotely How Online Documentation Works Transfer Protocols MISCELLANEOUS TOPICS . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Gear Shift Password Changes Command Abbreviations Additional Documentation v ====================== BASIC SYSTEM OPERATION ====================== Duties of the System Operator ----------------------------- The user-name for the System Operator is: SYSOP. You may prefer to sign up with your real name and set yourself at the highest user level (level 8). As the sysop, your main duty is to "validate" (grant membership to) new members. You do this with Sapphire's VALIDATE command. Signing on Locally ------------------ When Sapphire is waiting for a caller, press a key. This will "wake up" Sapphire, and freeze out the modem by putting it "off-hook". You can then sign on as if you had dialled up. If you don't want your phone off the hook, you can start up Sapphire in non-modem mode by selecting LOCAL in the SYSOP utility. This completely ignores anything to do with the modem. Signing on as SYSOP ------------------- The information presented below is based on the default set-up. For security reasons, the password shown here should be modified (using the BYE PASSWORD command) as soon as possible. 1. Wait until Sapphire is waiting for a visitor. 2. Press a key to wake it up. 3. When asked for your name, press Space-bar, then Return. 4. When you are asked for the password, type SYSOP then Return. You can then type Sapphire commands (the menu lists most of them; the HELP command lists all of them), or press some function keys... 1 Function Keys ------------- Sapphire's function keys are assigned as follows: REGULAR FUNCTION KEYS F 1 Function-key help. Also lists meanings of the status line icons. F 2 Enable Yoo-Hoo. Makes a noise when a specified person shows up. F 3 Removes 10 minutes online-time from whoever is connected. F 4 Adds on 10 minutes online-time to whoever is connected. F 5 Enable/Disable instant chat (type-to-sysop) via the CHAT command. F 6 Break in to chat with the person who is currently online. F 7 Not used. F 8 Not used. F 9 Modify number-of-hours-between-calls F10 Sound effects on/off. ALT FUNCTION KEYS F 1 Turn printer on and off (uses LPT1). F 2 Freeze out the person on the modem. You do this if you want to enter a few quick commands on his behalf but don't want him to see what you are typing. Press ALT-F2 again to restore communication. F 3 Subtract 1 from the membership level of the person who is signed on. F 4 Add 1 to the membership level of the person who is signed on. F 5 Announce mode on/off. In announce mode, nobody can log on. All people get to see is your sign-on logo, which is contained in the text file LOGOXX.STD. This lets you run your BBS as a "News and Announcements System". F 6 Send file. This is used to transmit a text file -- usually while chat- ting with a remote user. While the file is being transmitted, you can cancel, pause or slow down the output in the usual ways (spacebar, "P" or number keys, respectively). 2 F 7 Changes the name of the visitor to one that you specify. The new name is checked to prevent duplication. F 8 Instant banishment. Removes visitor from the valid caller list. If you change your mind before he logs off, you can hit F8 again to reinstate the user. F 9 Shut-down. If nobody is signed on, Sapphire ends immediately. If somebody is logged on, Sapphire will end when he or she logs off. F10 Turn Ultra-Mode on or off. Ultra-Mode is a kind of "Super-Sysop" mode. While in this mode, a user may... - Execute commands of any level - Use the CHANGE command on somebody else's message - Read all private messages - Call back in less than the usual time (Level 6+ can always do this) - Skip around a devalidation message at sign-on and proceed normally - Use the VALIDATE command on people at his level or higher The user named SYSOP is automatically in Ultra-mode. Other users -- even other Level 8 users -- must have it turned on explicitly by the ALT-F10 key. When ALT-F10 is pressed, a long, raucous sound is emitted from your computer's speaker. This tends to discourage people from hitting the key "by accident". The Status Line --------------- The top two lines of the Sapphire screen provide you with some information about what is going on. The top line lists membership level, time left, state icons (explained later), and the last item that went in the system log. The second line lists the member's sign-on name and full name, and phone number. The state icons are single-character indicators. You can think of them as on/off lights, if you wish. For an short description of each icon, press the F1 key. This displays a table describing each icon. Here is a more detailed explanation of each icon: Downwards-pointing triangle: The ALT-F9 key was pressed to put the system in "shutdown mode" and will be closed when it next disconnects (i.e. when the current visitor logs off). Infinity symbol (sideways 8): Ultra-mode is on. This is turned on and off by the ALT-F10 key. Diamond: The system is waiting for somebody in particular to show up. You can specify a list of names by pressing the F2 key. 3 Happy face: People who use the CHAT command will be placed directly in conversation, instead of seeing an "unattended" message. This is handy if somebody is online who usually asks you for a chat. Question mark: the current user entered the CHAT command to try to get in touch with you. The CHAT command makes a noise if you have sound turned on. Exclamation mark: You pressed the ALT-F6 key to put the system into "announce only" mode. People will only see the LOGOXX stock file before getting discon- nected. Double-note: Sound is on. Turn it on or off with the F10 key. Triple-line: Printer is active. The printer (which should be connected to the parallel port LPT1) is turned on or off by the ALT-F1 key. These icons may take a while to get used to, but before long, you'll be able to tell at a glance what's happening on your system. Online Validation and Banishment -------------------------------- ALT-F8 will banish the current visitor. However, the ALT-F8 key does not update the file until the member disconnects, so if you have a system crash, the file will still reflect the old value. In general, all data affecting a member's current session is lost if your system crashes, since the members information is written only "on the way out". For this reason, it is not possible for a sysop-level member to banish himself! If you press ALT-F8, but change your mind before the user logs off, you can press the key one more time to reverse your decision. Yoo-Hoo and Rename ------------------ If you intend to run a BBS that does not tolerate aliases, but insists that people use real names, the combination of F2 (Yoo-Hoo) and ALT-F7 (Rename) will prove useful. When you press the Yoo-Hoo key, you will be prompted to enter a list of names, separated by slashes. For example, you might enter: Robert Libman/Rene Levesque/Elizabeth Mountbatten-Windsor When somebody signs on under any of the indicated names, Sapphire will make a distinctive noise to alert you. 4 You can then break in (using F6 -- Chat) and tell the person that you are changing his sign-on name to his real name. This can be done with the Rename key. The Rename function will not allow you to change the name to an existing name. Thus, if you already have a John on your system, you can't change somebody else's name to John. 5 ================ AUTO-MAINTENANCE ================ Sapphire is designed to perform all maintenance tasks automatically. The following "maintenance" sections are simply an explanation of how it does this, so if you are browsing this manual for the first time, you can safely skip them without any problem. User File Auto-Maintenance -------------------------- The user file will hold up to 350 user names. When a new user signs up, Sapphire looks for an inactive user to replace. The higher the level of the member, the longer it takes for him to be considered inactive. Here are the required call-back times: Level Time-Out (Days) Member Level Description 1 10 Non-Member 2 50 Basic Member 3 60 Special Member 4 70 Top Notch Member 5 80 Inner Circle Member 6 90 Aide-de-Sysop 7 100 Co-Sysop 8 110 Sysop Note that this is only the time after which a user is eligible for replacement. If there are no new sign-ups to replace his name on the list, his user-record can remain valid forever. The user named SYSOP is never eligible for replacement. Message File Auto-Maintenance ----------------------------- Sapphire maintains 225 message files. When the last one is used up, the first one is replaced, thereby "deleting" the oldest one. All messages share the same space. There is no way to preserve a message permanently. If you have something you want to keep available for a long time, place it in the library directory as a .TXT file and tell the members to use the LIBRARY command to review it. 6 If you have to get rid of a message, use Sapphire's ERASE command. There is no need to use DOS DEL or ERASE. Library Auto-Maintenance ------------------------ Any .TXT file that appears in the Library directory will appear on the Library list. The 39-character description of each article is taken from the first line of each file (leading blanks are ignored). Thus, you can add to the Library simply by copying text files into the Library directory, and remove articles using the DOS DEL command. For your members' convenience, you might sort the directory in reverse-date order, using a utility such as Norton's DS command. Files Auto-Maintenance ---------------------- Sapphire maintains a list of up to 500 uploads. When the list is full, programs are dropped from the list and deleted from the file directory accord- ing to a formula based on: (A) Number of times the file has been downloaded (B) How many days have elapsed since the last request (C) How many days the file has been on the list In other words, Sapphire will identify and replace the least popular file. All files are protected from this auto-maintenance if they have seen some activity (download, or the initial upload) in the past 14 days. 7 ==================================== CUSTOMIZING YOUR SYSTEM'S APPEARANCE ==================================== Sapphire comes preconfigured as a "private online conversation club" named "The Pinnacle Club". Some Sapphire sysops find this approach appropriate to their requirements, so there are a few Pinnacle Clubs around the world. After running the basic system for a while, many sysops decide to fine-tune its function and appearance to suit their needs... An Overview of Your Customization Options ----------------------------------------- There are several areas of customization for you to consider, which are listed below in order of increasing difficulty: 1. Configuration 2. Application 3. Hardware 4. Stock files 5. Message bases 6. Doors and events 7. Custom programming These are described, in order, below. 8 Option 1. Configuration ------------------------ The configuration program (CONFIG on the main menu of the SYSOP utility) lets you specify some general information about your hardware and how you want your BBS to run. In particular, you may wish to change some of the following items: 1. Settings on the console ("Video settings" on the CONFIG menu) - Use of color - Number of lines displayed on the console (25, 43, or 50) 2. General preferences - Console sound on/off - Key click at the console - Phone number format (e.g. 999-999-9999 or (999) 999-9999) - Command prompt (e.g. ==> or "Enter your command now") 3. User settings ("Sign-up and security" on the CONFIG menu) - Minimum baud-rate to sign on - Length of time a user may spend on the system Option 2. Application ---------------------- In deciding how to customize your system, you should keep in mind what goals you have set. For example, if you are running a purely conversational system, your users will benefit more from hearing your thoughts on the current topic than they will if you spent time writing online documentation. Similarly, if you are running a files system, your users want files, so your time may be well spent reading shareware catalogs, or calling other systems. In other words, sometimes the best customization is none at all. Because when you come right down to it, BBS's are about people interacting, not text files. In order to best support your system's goals, you may decide to change the privileges accorded the various membership levels. For more information about this, see the chapter entitled "Designing Membership Levels". 9 Option 3. Hardware ------------------- Without a doubt, the easiest way to improve your BBS is to add a faster modem. This attracts more members -- especially those who own fast modems, since they tend to avoid systems that now seem "slow". Since people can move more data in less time, the traffic on your system picks up, which in turn attracts more traffic. Sapphire supports modem speeds up to 19200, although at higher baud-rates you may find that you need a faster computer. For example, although an old 4.77 Mhz XT can support 9600 baud calls, it doesn't actually send the text out at that speed; the connection will look more like a 2400-baud connection. TECHNICAL NOTE: The current version of Sapphire does not explicit- ly support "locked baud rates", but you can simulate it by setting all but one connect string to "XXX" (i.e. some nonsense string) and the locked baud-rate as "CONNECT". This will cause all connections to be interpreted as a connection at that speed. In order to do this, though, you must be sure that your computer can support the locked baud-rate. For example, you could not lock at 4.77 MHz XT at 9600 baud; it would miss characters. If you are running a file-transfer system, you can improve it by increasing the disk space. When you increase your disk capacity, you should set your related configuration items ("upload free space" and "maximum files") accordingly, using the CONFIG option of the SYSOP utility. Option 4. Stock Files ---------------------- The easiest and most immediately gratifying way to customize your system is to modify the "Stock files". These are explained in the chapter entitled "Stock Files". Option 5. Message Bases ------------------------ A "message base" is a logical grouping of messages. For example, if your system catered to dog breeders, you might group messages about Dalmatians separately from messages about Spaniels. Thus, somebody with no interest in Dalmatians would not have to read messages about that breed of dog. In the preceding example, the messages were grouped by subject ("breed of dog"). You may decide to group messages by some other criterion, such as how 10 long the person has been a member of your system, or how much they paid to join. Sapphire is initially configured with 5 general message bases, which group messages according to membership level. That is to say, a Level 1 (lowest) member has access to no message bases, a Level 2 member has access to one message base, and so on. A Level 5 member has access to 5 message bases. (The sysop, at Level 8, has access to all message bases.) These message bases, along with three other special-case message bases, are defined in a text file named MESSAGES.DEF. You can edit this file with a standard text editor, such as DOS's EDLIN or EDIT, a programmer's editor, or a word-processor in non-document (generic DOS text) mode. The format of the file is literally self-explanatory, since the file itself contains an explanation of its format. In order to view the file, enter the following command at the DOS prompt: SEE MESSAGES.DEF The SEE command can also print the file. Before you modify the file, it is a good idea to either print it out or make a backup copy. You can make a backup copy by entering the following DOS command: COPY MESSAGES.DEF MESSAGES.OLD This creates a second copy of the file, named MESSAGES.OLD. Thus, if you make a mistake and Sapphire no longer understands the file, you can restore it to its original form with the command: COPY MESSAGES.OLD MESSAGES.DEF In general, the MESSAGES.DEF file allows you to define up to 15 message bases (including logon announcements, feedback to sysop, and E-Mail). After modifying the MESSAGES.DEF file, log on and use the command ==> BASES to verify that the messages bases are set up the way you want. You can use the level-change function keys (ALT-F3 and ALT-F4) to try the BASES command at each membership level. Option 6. Doors and Events -------------------------- Doors and Events are covered in their own chapter, "Doors and Events", pre- sented later in this manual. 11 Option 7. Custom Programming ----------------------------- You might find that Sapphire is excellent for your application, but needs just one little change to make it perfect. For example, you may have an idea for a new command that you think your users would find exciting. In such case, you will require some custom programming. We can do it for you, or -- if you are familiar with Turbo Pascal -- you can do it yourself. There is, of course, a cost associated with custom programming, but this cost can frequently be lowered if your idea can be applied to other customers' systems. For example, Sapphire's file download and message reading systems were largely influenced by custom work. Since in each case the customer had a good idea, we performed the modifications for an extremely low price. Similarly, if you wish to purchase a source code license to make the modifica- tions yourself, we are willing to offer discounts if your work has a wider application. If you have a good idea and you are handy with Turbo Pascal, give us a call! 12 ============================= CUSTOMIZING MEMBERSHIP LEVELS ============================= Overview of Membership Levels ----------------------------- Sapphire supports 8 membership levels. In general, these levels function as follows: Level 1 Non-members Levels 2-5 Members Levels 6-8 System operations staff Each membership level has a set of privileges associated with it: - Message bases that can be read (see previous chapter) - Commands that can be used For example, as initially configured, Sapphire provides a non-member (Level 1) with the SEND command, but no READ command. This means that a non-member can ask for greater access privileges ("tell us a bit more about yourself, please!") but can not really use the system (i.e. read messages). A basic member (Level 1) gets the READ command and (as defined in the MSGBASES.DEF file) gets to use one message base. The initial setup described above works well, because it forces new users to type in a message. You'll find that you can judge just by reading that one message, whether or not to make the person a full member. Why Change Anything? -------------------- No BBS design works for everybody! You may find it necessary to change the initial configuration. For example, if you are a shareware author, you might want to make the GET (i.e. download software) command available to non-members, so that people can obtain your software without waiting around to become a full member. 13 Or you might decide to give non-members their own message base, so you can watch them in action. You could give them access to a message base by modify- ing the MSGBASES.DEF file (as explained in the last chapter), but you would also have to give them access to the READ command. You would do this by modifying the COMMANDS.LEV file. The COMMANDS.LEV File --------------------- COMMANDS.LEV is a text file that defines the minimum membership level required for each of the internal (non-door) commands that Sapphire supports. You can edit COMMANDS.LEV with a standard text editor, such as DOS's EDLIN or EDIT, a programmer's editor, or a word-processor in non-document (generic DOS text) mode. The format of the file is literally self-explanatory, since the file itself contains an explanation of its format. In order to view the file, enter the following command at the DOS prompt: SEE COMMANDS.LEV The SEE command can also print the file. Before you modify the file, it is a good idea to either print it out or make a backup copy. You can make a backup copy by entering the following DOS command: COPY COMMANDS.LEV COMMANDS.OLD This creates a second copy of the file, named COMMANDS.OLD. Thus, if you make a mistake and Sapphire no longer understands the file, you can restore it to its original form with the command: COPY COMMANDS.OLD COMMANDS.LEV After modifying the COMMANDS.LEV file, log on and use the command ==> HELP S to verify that the commands are set up the way you want. You can use the level-change function keys (ALT-F3 and ALT-F4) to try the HELP command at each membership level. 14 Default Membership Design ------------------------- Before designing your membership levels, you may find it helpful to understand our rational is designing the default setup. This is explained below. Level 1: Non-member May post: Non-member message base Commands: BYE Disconnect from system (i.e. logoff) HELP Display a list of commands you can use INFO Membership requirements for this system SEND Leave a message for other users to read SPECS Change the way things look around here TIME Display how much time is left for visit VERSION Display software version and copyright Comments: Note the absence of the READ command. Note also that we do NOT put the BASES command at this level. New users who try out that command tend to get miffed and log off. It's better for them to read the INFO article, and thus get some idea of what you are trying to accomplish with your system. Note: The BYE, TIME and VERSION command are locked at level 1 and can not be assigned to a different membership level. 15 Level 2: Basic Member May post/read: Non-member and Basic member message bases May post: Feedback to Sysop message base May read: Report from Sysop message base Added commands: EXPERT Switch between casual and expert mode BASES Summary of message bases you can use GIMMICKS Describes various tricks for messages GRAPHICS Switch graphic characters on and off HINTS Tricks and tips for using this system LIBRARY Browse and read in our online library MESSAGES Quick summary of messages (time & user) NAMES Specify names for selecting READ etc. PROTOCOL Select method used for file transfer READ Read new messages left by other users REVIEW Inspect a single message by DATE:MINUTE SET Modify the DATE:MINUTE for READ command TEXT Specify text to reduce READ output etc. USERS Display information about our users Level 3: Special Member Added base: Special Member Added commands: ACTIVITY Display system activity for past 7 days CHANGE Modify a message you've sent previously FILES List software available for downloading GET Get some software from our collection GIVE Contribute software to our collection MOVE Move a message from one base to another Level 4: Top Notch Member Added base: Top Notch Added commands: CHAT Page system operator for a conversation OBSERVE Overview of logon/logoff activity, etc. Comments: Note that lower-level members, when doing the USERS command, see Top Notch members listed as "Special". Top Notch messag- ing is completely hidden from lower levels. The idea here is to avoid displaying membership-level differences where it is not relevant, while providing higher-level members with a measure of privacy. 16 Level 5: Inner Circle Member Added base: Inner Circle Added commands: None Comments: Lower-level members, when doing a USERS command, see an Inner Circle member listed only as "Special" (or "Top Notch", in the case of Level 4 members). Inner Circle messaging is hidden from lower levels. See Level 4 for explanation. Level 6: Aide-de-Sysop Added commands: ERASE Remove message (resets it to time 0:0) Comments: This level of authority allows people to keep the system tidy without having access to personal member information, such as phone numbers. Level 7: Co-Sysop May read: Feedback to Sysop Added commands: BANISH Devalidate user (remove from user list) DOORS Update your list of "Door" programs DOS Shell out to DOS; type "EXIT" to return DUMBTERM Start dumb terminal for outgoing calls EVENTS Schedule your BBS's close-down events PROBE Display user info (see also USERS cmd) VALIDATE Grant a user a higher membership level Comments: At this level, the USERS command gives more detailed informa- tion, such as password and phone number. A co-sysop can run the entire system remotely. He can not, however, find out the sysop's password. Level 8: Sysop May post: Logon Announcements Added commands: CLOSE Shut down system; prevent further calls Comments: The user named "SYSOP" is automatically placed in "Ultra- Mode". See the explanation of "Ultra-Mode" (Alt-F10) in the "Function Keys" section. 17 ======================= CUSTOMIZING STOCK FILES ======================= Stock files are files that contain "stock" (i.e. generic) text -- material that is displayed frequently. For example, the BBS sign-on logo is contained a stock file (named LOGOXX.STD). The welcoming message is also contained in a stock file. And so on. To modify a stock file, you need a text editor, such as DOS EDLIN or EDIT, or a programmer's editor, or a word-processor in non-document (generic DOS text) mode. Each stock file contains text, and sometimes contains comments; any line that begins with a semi-colon is not displayed when the stock file is shown. In order to browse through the various stock files, enter the following command at the DOS prompt: SEE *.STD This will let you select and display all files with a STD extension. (Stock files also use the GRA extension.) The SEE command can also print the file. Before you modify the file, it is a good idea to either print it out or make a backup copy. You can make a backup copy by entering the following DOS command: COPY *.STD *.OLD This creates a second copy of each stock file, named <filename>.OLD. (For example, LOGOXX.STD would be duplicated in LOGOXX.OLD) Thus, if you make a mistake and Sapphire no longer understands the file, you can restore it to its original form with the command: COPY <filename>.OLD <filename>.STD 18 The Two Types of Stock Files ---------------------------- Stock files come in two varieties, identified with the .STD and .GRA file extensions... EXTENSION MEANING --------- ------- .STD Contains standard ASCII (no value greater than 128) .GRA Contains IBM-PC extended ASCII ("graphics") For example, a standard stock file might be named MAINXX.STD, while its graphic equivalent would be named MAINXX.GRA. A user will normally see only the standard stock files (i.e. those with a STD extension). However, the user can use Sapphire's GRAPHICS command to turn on the GRA stock files. The current version of Sapphire does not explicitly support full ANSI stock files (e.g. color changes and animation). The next version will address this need. For a description of the purpose of each stock file, select the INFO section on the SYSOP utility main menu, then select FILES. Drawing with Graphic Characters ------------------------------- In order to put graphic (extended ASCII) characters into a .GRA stock file, you can use one of the following methods: 1. Press and hold the ALT key, followed by three digits on the numeric keypad. This lets you enter any extended ASCII character. For example, to enter a solid block character, hold down ALT then press (on the numeric keypad) 2, then 1, then 9. Release the ALT key. The problem with this method is that it is more than a little cumbersome, and it does not work on all machines. Also, some pop-up (TSR) programs prevent it from working. 2. Define the graphics characters via a keyboard macro program, such as Cruise Control, NewKey, PRD+, ProKey, SmartKey or SuperKey. If you would like an example of how we set up SuperKey macros to perform this task, just drop us a line asking for our SuperKey PC-ASCII macros, enclosing $3 to defray the cost of the disk and postage. 19 Note that ANSI animator programs (such as TheDraw) are NOT appropriate for creating GRA stock files. GRA files are ordinary text files, except that they use extended ASCII. This has two benefits: 1. The files transmit quickly (ANSI is notoriously slow). 2. People dialling in can scroll back and see the screens. (Many terminal programs do not reinterpret ANSI when scrolled back, resulting in some user confusion.) Stock File Naming Convention ---------------------------- Most of the files that come with Sapphire follow the naming format of four characters and two X's for the root name (e.g. LOGOXX.STD). These files will be displayed to any user who encounters the situation in which it is appropri- ate to display the stock file. But you can exercise a measure of control over which files get displayed, depending on how you name the stock files. The "XX" part of the file name holds the key: FORMAT: AAAABC.DDD EXAMPLE#1: UPFNXX.GRA EXAMPLE#2: MAINX1.STD In the FORMAT given above, the letters have the following meaning: AAAA Four letters identifying the purpose of the stock file. In the examples, UPFN is the file that is displayed when the user has to supply an UPload File Name. MAIN is displayed as the MAIN menu. B User membership level (1 to 8) C User expertise level (1 to 3) DDD File extension (STD or GRA -- as explained previously) Whenever Sapphire has to display a stock file, it will first try to find a file that matches the user membership and expertise level. Thus, a level 3 user with expertise set at level 1 would see a file named MAIN31.STD when it is time to show the main menu. That is to say, he would see the file if it existed. If it does not exist, Sapphire tries to find a file that matches but has an X in one or both positions. It will then pick the one that matches best. 20 EXAMPLE: User is at membership level 4, expertise 3. FILES: MAIN43.??? would be shown (??? here means STD or GRA) MAIN4X.??? would be shown if MAIN43.??? didn't exist MAINX3.??? would be shown if the previous two didn't exist MAINXX.??? would be shown if none of the previous existed Nothing would be shown if none of the previous existed The final line introduces an important concept in the use of stock files. By leaving out XX files for a given stock file application, you will prevent certain people from seeing that type of file. The most obvious application is for the main menu. Only MAINX1 is defined, which means that any membership level can see that file, but only if their expertise level is set to 1. If their expertise level is set to 2 or 3, they will NOT see a menu. You may wish to define some additional main menus. This is, in fact, an ideal way to get familiar with stock file operations. In order to provide complete coverage of all membership and expertise levels, you could define the following 48 files (where ??? means both a STD and GRA file): MAIN11.??? MAIN12.??? MAIN13.??? MAIN21.??? MAIN22.??? MAIN23.??? : : : : : : MAIN71.??? MAIN72.??? MAIN73.??? MAIN81.??? MAIN82.??? MAIN83.??? In actual practice, however, you probably won't define menus for users at expertise level 2 or 3, so you'll actually define the following files... MAIN11.??? to MAIN81.??? which is a more manageable task -- only 16 files. 21 Stock File Commands ------------------- Stock files can contain, apart from text, special lines that the user does not see. These are as follows: COMMAND EXAMPLE MEANING ------- ---------------- -------- ;<space> ; Hello world! A comment ;<number> ;8 Keep following lines together on screen ;LOG text ;LOG Pistachio Places text in the system (OBSERVE) log ;FNC color ;FNC WOE Sets functional color of file display The comment and log functions are self-explanatory. You can find examples of both in the file UPDFXX.STD, which is the stock file that is displayed when the user tries to upload and there is not enough free space on the disk. In such case, you want to log this fact to the OBSERVE log so that you will find out about it when you read the log later on. The "semicolon number" command is known as "The Keep Command". It is used when you want to ensure that certain text in a stock file is kept together on one screen, instead of being broken in the middle with a "More, Notepad, Quit" prompt (which is displayed when the screen is full). Let's say you had placed, in a stock file, a list of phone numbers that was 8 lines long. It would be annoying to the reader if it was broken up in the middle. So you could start the table like this: ;8 PHONE NUMBER CONTACTS ------------ -------- 514-345-9578 Pinnacle Voice Support 514-345-8654 Pinnacle Free Files BBS : etc. The ;8 line will ensure that the next 8 lines are always presented on the same screen, even if it means presenting the "More, Notepad, Quit" prompt a little early. For examples of the keep command, refer to the stock file HINTXX.STD. 22 The "functional color" command lets you specify the color of the following text. Normally, stock files are displayed in light grey. You can switch colors by using the ;FNC command. The command works this way: COMMAND COLOR USED THEME OR FUNCTION ------- ---------- ----------------- ;FNC HLP Yellow Helpful or explanatory information ;FNC INP Light Cyan User input ;FNC QUE Light Green Text preceding user input (a prompt) ;FNC WOE Light Red Something unusual or troublesome is happening ;FNC INF Green Regular information and progress messages ;FNC FIL Light Grey Stock and message file output ;FNC HDG Light Blue A heading or title ;FNC INI Light Grey Initializes an alternating-color list ;FNC LIS LtGry/Cyan Switches to opposite color in list ;FNC HEY Lt Magenta Emphasized output By defining colors using this method (which we call "thematic color specifica- tion") we make possible the rapid reconfiguration of color on the BBS. The value of this is not immediately obvious, because color redefinition is a feature planned for the next version of Sapphire. (See the "NEXT" item on the INFO menu of the SYSOP utility for details.) For the time being, it does mean that you can control the color of stock files so that they do not always appear in Light Grey. The INI and LIS colors are a little different from the others. When you specify INI, it initializes "list color processing". Thereafter, every time Sapphire sees ;FNC LIS it will switch between Light Grey and Cyan. This technique is very handy for distinguishing lines in a list. 23 ================ DOORS AND EVENTS ================ The information presented in this chapter is addressed to experienced sysops. If you are new to the joys of sysoping, it would probably be best to avoid the DOORS and EVENTS commands until you are more familiar with your new BBS. Sapphire will function perfectly well without DOORS and EVENTS installed, so you can safely skip this chapter and come back to it later. Definitions ----------- Doors and events are both instances where the Sapphire program ends and control is returned back to DOS. In the case of a door, the shut-down is initiated by a user; for events, the shut-down happens automatically, according to a schedule you set up. Applications for Event Processing --------------------------------- Consider the following batch file. (Note that the <-- arrow and following text are comments, not part of the batch file.) REM Batch File Autoback :START <-- A batch file "label" SRUN <-- The main Sapphire program COPY SAPPHIRE.USR A:SAPPHIRE.USR <-- Copy the user list GOTO START <-- Start over again If you could arrange to have the BBS come down every night at 3:00, it could make a spare copy of the user list on the A: drive. This would be very useful, although of course you would have to make sure that the A: drive always had a floppy inserted and ready to go! Set up in this way, you could leave town for a long weekend, confident that your user list was being backed up every day. This is only a very simple example of the benefits of event processing. Another possible application is automatic dial-out via your favourite communi- cations program (to pick up mail, perhaps). Of course, you would have to write a "script" (i.e. a program that your comm program understands) in order to have it dial out, sign on, pick up the mail, then return to DOS. 24 One very common use for event processing is to support network systems such as Fido -- a very complicated topic beyond the scope of this manual. Applications for Doors Processing --------------------------------- A door is an external program that a user can run from Sapphire. (It is, in effect, a "door" into programs written by other people.) There are dozens of door programs available. One example is the Pyroto Mountain gaming system, which was also written by Pinnacle Software. You can call it as a door, giving your members a chance to play this intriguing game of magic and politics. We also publish the Free Speech "open forum" system, which can be run as a door. Before making a door available to your members, you should review it carefully. The quality of door software varies greatly; some may crash, thereby failing to return to DOS and consequently taking your BBS "off the air". In order to run most doors (i.e. those not created by Pinnacle Software), you will require a door-data conversion program such as DoorMaster or DoorWay or a specific converter program such as SP2QBBS. The latest version of these converters can usually be obtained on your local or national BBS, or from a telecomputing service such as GEnie or CompuServe. Coding Your Batch Files ----------------------- In an environment using doors and events or both, everything is tied together with batch (.BAT) files. (For detailed information about batch files, consult your DOS reference manual.) The simplest kind of batch file was illustrated in the "automatic user list back-up" example shown earlier. This was a just a loop, executing one func- tion. One problem, though ... you'll note that there was no way to get out of the loop! So it was not a particularly useful program. If you want to call Sapphire from any directory, put a batch file like the following one (which you could call S.BAT) in one of the directories in your PATH: ECHO OFF <-- Stop display of batch lines C: <-- Change to the right drive CD \SAPPHIRE <-- Change to your Sapphire directory SAPPHIRE %1 %2 <-- Jump to batch file SAPPHIRE.BAT 25 SAPPHIRE.BAT is a batch file that comes with Sapphire. It looks like this: ECHO OFF <-- Stop display of batch lines SAPPHIRE %1 %2 <-- Start up Sapphire EXTERNAL <-- Jump to batch file EXTERNAL.BAT This batch file must be in the directory where SRUN.EXE resides. The %1 and %2 after the SAPPHIRE allows you to pass parameters to Sapphire, so you can start up the batch file with SAPPHIRE LOCAL to run without a modem. (This is how the SYSOP utility does it.) How EXTERNAL.BAT Works ---------------------- Don't look for a file named EXTERNAL.BAT in the Sapphire package -- there isn't one. EXTERNAL.BAT is created whenever Sapphire ends. If Sapphire is shutting down because you are closing it (using the CLOSE command, for example), EXTERNAL.BAT will be empty. As a result, you'll drop straight through to the DOS prompt. For doors and events, however, Sapphire copies other batch files into EXTER- NAL.BAT. So whatever was in those other batch files will get executed. But how does this get us back to Sapphire? After Sapphire copies the other batch file into EXTERNAL.BAT, it appends some additional instructions, as in this example: C: <-- Switch to Sapphire's "home" drive CD \SAPPHIRE <-- Switch to Sapphire's "home" directory SAPPHIRE <-- Jump to the SAPPHIRE.BAT batch file And thus, the circle is completed. Of course, the extra instructions may vary, depending on where your copy of SRUN.EXE resides and the way you started up Sapphire. 26 Batch Templates --------------- You will use the DOORS and EVENTS commands to specify which batch files will be copied to EXTERNAL.BAT. We will call these files "Batch Templates", because although they end in .BAT, they are never actually run directly. You can write the templates without regard to what happens after the program ends, because that's taken care of when Sapphire copies them to EXTERNAL.BAT. NOTE: A template must not call another batch file, unless that batch file contains the code to get back to SAPPHIRE.BAT. You can, however, use the batch file command "CALL", which is explained in your DOS reference manual. For example, to call up the PYROTO door, you could write a template file named PYROTO.BAT, which looks like this: C: <-- Make sure you are on the right drive CD \PYROTO <-- Change to the Pyroto directory PYROTO <-- Start up the program Writing Door and Event Programs ------------------------------- When Sapphire calls a door or event, it always creates a file in the root directory of the drive containing Sapphire, named: SAPPHIRE.DAT This file contains important information for doors and events. If you plan to write door or event programs, you'll need access to this data. Turbo Pascal source-code, describing the layout of the file, can be found in the file named SDOOR.INC. 27 ============= FILE TRANSFER ============= What is File Transfer? ---------------------- With Sapphire's file-transfer feature installed, you will be able to exchange software with people who dial into your system, using the popular Xmodem, Ymodem and Zmodem protocols. Sapphire maintains a list of up to 500 programs (providing there is enough space on your hard disk), along with statistics and documentation. The file-transfer feature requires a system equipped with a hard-disk with a minimum of 1 Megabyte free space. Installing File Transfer ------------------------ In order to enable file-transfer (Xmodem, Ymodem and Zmodem), you must install the DSZ file-transfer program, which is included in the Sapphire package with the permission of its author, Chuck Forsberg. In order to install DSZ, select the DSZ option on main menu the SYSOP utility. This will enable the GET, GIVE, PROTOCOL or FILES. Adding Software Locally ----------------------- To add a file to the software collection while you are at the console, you must first place it in the files directory (usually named C:\SAPPHIRE\FILES). Sapphire's DOS command comes in handy, here, for moving files around. Afterwards, use the GIVE command. For example, if you had moved the file PYROTO.LZH into the files directory, you would then enter this command: ==> GIVE PYROTO.LZH You would then be asked who this file is for (everybody, sysop, etc.), then asked to write some documentation about the file. (This step is described later, in more detail.) 28 Adding Software Remotely ------------------------ A remote user follows essentially the same steps as a local user, but obviously he cannot place the file directly into the files directory. So he must upload the file, using one of the file-transfer protocols used by Sapphire (Xmodem- Checksum, Xmodem-CRC, Ymodem, Zmodem). As a reward for contributing software, he is granted "double-your-minutes-back for this visit and the next". For example, if it took him 10 minutes, he gets an extra 20 minutes for the current visit, plus 20 extra minutes for the next session. How Online Documentation Works ------------------------------ After contributing a file, the contributor may write up to 48 lines of documen- tation, which other people will be able to read before deciding whether or not to download this file. Online documentation that has already been written can be re-used. For example, if you are making available a multi-file software package, you can tell Sapphire to use one documentation file for all of the files. Incidentally, if one of those software files is deleted, the documentation file is retained -- as long as some other file is using it. The documentation step uses the usual text editor that you use for writing messages. No new skills need be learned. In fact, you can even include private and exclusive messages in your documentation. NOTE: If the entire documentation is private (i.e. the first line, or the summary line are private), then the file can be accessed only by the people listed in the private header. This enables you to exchange files privately with a limited group of people. The documentation is saved in the files directory, in a file with the same root-name as the original file. For example, a file named VARITALE.ARC would have a documentation file named VARITALE.S-D associated with it. (S-D stands for Software Documentation.) If you don't like the documentation that a user has written, you can copy some better documentation over the S-D file. All S-D files are standard text files, prepared with a text editor. 29 Transfer Protocols ------------------ The Ymodem supported by Sapphire is proper Ymodem, per the original specific- ation. Some very respectable communications programs confuse the protocol Xmodem-1K with Ymodem. If your users complain that Ymodem doesn't work for them, suggest they switch their communications program from Ymodem to Ymodem- Batch. You should encourage your users to use the Zmodem protocol, because it has built-in crash recovery. That means that if the user is cut off while down- loading a file, he can pick up where he left off. Crash recover also works on uploaded files. If the user is disconnected during an Xmodem or Ymodem transfer, Sapphire has no choice but to delete the partial file. If the user used Zmodem, though, Sapphire retains the partial file in the files directory -- though it does not add it to the files list. This enables the user to call back and pick up where he left off, using Zmodem's crash recovery. 30 ==================== MISCELLANEOUS TOPICS ==================== Gear Shift ---------- Sapphire supports adjustable output speed. During output, a user can press one of the number keys to "shift gears" for a comfortable reading speed. The keys run from 1 (slow) to 9 (fast). The 0 key is the "top gear" key. It sets output speed to maximum. When the main command prompt comes up, output is reset to full speed. This has proven to be a convenient arrangement. However, the user can reset his "default gear", via the SPECS command. Certain types of line-noise problems have been solved by selecting a lower output speed. Password Changes ---------------- There is an undocumented feature in Sapphire which allows users to change their passwords. If you sign off by typing BYE PASSWORD (no abbreviations) you will be asked for a new password. This feature was not explicitly documented because there has long been an argument among computer security experts about the wisdom of letting users change (or even select) their passwords. It might be best to keep the BYE PASSWORD feature secret if you give users a new password when you validate them. Or perhaps you'll decide to avoid letting them change their password simply because they tend to forget what their new password is. Whether or not you let your users know about this feature is up to you. Command Abbreviations --------------------- If Sapphire forced users to type every command in full, the advantages of using words (instead of single letters, as other BBS's do) might seem unimportant. Fortunately, Sapphire lets users abbreviate and stack commands. These tech niques are described online, by the HINTS command. 31 Additional Documentation ------------------------ You can find additional information about Sapphire in the SYSOP utility (enter SYSOP at the DOS prompt). In particular, refer to two sections: 1. The INFO menu provides a wide variety of information about Sapphire and also lets you print the order form, so you can register your copy of Sapphire. 2. The CONFIG program has pop-up help for each field you can con- figure. There is a lot of useful information here, which you might find interesting to read even if you don't change the configured values. 32